Frontendowa Brama API: Federacja GraphQL i Schema Stitching

W świecie nowoczesnego tworzenia aplikacji internetowych, zarządzanie danymi z wielu źródeł może stanowić poważne wyzwanie. W miarę jak aplikacje stają się coraz bardziej złożone i przyjmują architekturę mikrousług, potrzeba zunifikowanego i wydajnego sposobu dostępu do danych staje się kluczowa. Frontendowa Brama API (Frontend API Gateway) działa jako centralny punkt wejścia dla aplikacji klienckich, agregując dane z różnych usług backendowych i zapewniając uproszczone doświadczenie zarówno dla deweloperów, jak i użytkowników końcowych. Ten wpis na blogu omawia dwie potężne techniki budowania frontendowej bramy API: Federację GraphQL i Schema Stitching.

Czym jest Frontendowa Brama API?

Frontendowa Brama API to wzorzec architektoniczny, w którym dedykowany serwer działa jako pośrednik między klientami frontendowymi (np. przeglądarki internetowe, aplikacje mobilne) a wieloma usługami backendowymi. Upraszcza pobieranie danych poprzez:

• Agregowanie danych: Łączenie danych z wielu źródeł w jedną odpowiedź.
• Transformowanie danych: Dostosowywanie formatów danych do potrzeb frontendu.
• Abstrakcję złożoności: Ukrywanie zawiłości usług backendowych przed klientem.
• Wymuszanie bezpieczeństwa: Implementowanie polityk uwierzytelniania i autoryzacji.
• Optymalizację wydajności: Buforowanie często używanych danych i redukowanie liczby żądań sieciowych.

W gruncie rzeczy, implementuje ona wzorzec Backend for Frontend (BFF) na dużą skalę i daje zespołom frontendowym większą kontrolę nad API, z których korzystają. W większych organizacjach, posiadanie przez frontend możliwości zarządzania i kuratorowania własnych API może prowadzić do szybszego dostarczania oprogramowania i zmniejszenia zależności od zespołów backendowych.

Dlaczego używać GraphQL dla Frontendowej Bramy API?

GraphQL to język zapytań dla API oraz środowisko uruchomieniowe do realizacji tych zapytań przy użyciu istniejących danych. Oferuje on kilka zalet w porównaniu z tradycyjnymi API REST, co czyni go idealnym do budowania frontendowych bram API:

• Wydajne pobieranie danych: Klienci żądają tylko tych danych, których potrzebują, co redukuje nadmiarowe pobieranie (over-fetching) i poprawia wydajność.
• Silne typowanie: Schematy GraphQL definiują strukturę danych, co umożliwia lepsze narzędzia i walidację.
• Introspekcja: Klienci mogą odkrywać dostępne dane i operacje poprzez introspekcję schematu.
• Możliwości czasu rzeczywistego: Subskrypcje GraphQL umożliwiają aktualizacje danych w czasie rzeczywistym.

Wykorzystując GraphQL, frontendowa brama API może zapewnić elastyczny, wydajny i przyjazny dla deweloperów interfejs do dostępu do danych z wielu usług backendowych. Kontrastuje to wyraźnie z tradycyjnymi podejściami wykorzystującymi wiele punktów końcowych REST, z których każdy musi być odpytywany indywidualnie i często zwraca więcej danych niż jest to wymagane.

Federacja GraphQL: Podejście Rozproszone

Czym jest Federacja GraphQL?

Federacja GraphQL to potężna technika budowania rozproszonego API GraphQL poprzez komponowanie wielu usług GraphQL (nazywanych „podgrafami”) w jeden, zunifikowany schemat. Każdy podgraf jest odpowiedzialny za określoną domenę lub źródło danych, a brama federacyjna orkiestruje zapytania między tymi podgrafami.

Główna koncepcja opiera się na supergrafie, pojedynczym, zunifikowanym schemacie GraphQL, który reprezentuje całe API. Ten supergraf jest budowany przez komponowanie mniejszych schematów GraphQL, zwanych podgrafami, z których każdy reprezentuje konkretną mikrousługę lub źródło danych. Brama federacyjna jest odpowiedzialna za kierowanie przychodzących zapytań GraphQL do odpowiednich podgrafów i łączenie wyników w jedną odpowiedź.

Jak działa Federacja GraphQL

1. Definicja podgrafu: Każda mikrousługa udostępnia API GraphQL (podgraf), które definiuje własne dane i operacje. Schematy te zawierają dyrektywy, które informują bramę federacyjną, jak rozwiązywać typy i pola. Kluczowe dyrektywy to `@key`, `@external` i `@requires`.
2. Kompozycja supergrafu: Brama federacyjna (np. Apollo Gateway) pobiera schematy z każdego podgrafu i komponuje je w jeden, zunifikowany schemat (supergraf). Proces ten obejmuje rozwiązywanie konfliktów typów i pól oraz ustanawianie relacji między typami w różnych podgrafach.
3. Planowanie i wykonywanie zapytań: Gdy klient wysyła zapytanie GraphQL do bramy, brama analizuje zapytanie i określa, które podgrafy muszą zostać odpytane, aby zrealizować żądanie. Następnie rozdziela zapytanie do odpowiednich podgrafów, zbiera wyniki i łączy je w jedną odpowiedź, która jest zwracana do klienta.

Przykład: Platforma E-commerce z Federacją GraphQL

Rozważmy platformę e-commerce z oddzielnymi mikrousługami dla produktów, klientów i zamówień.

• Podgraf produktów: Zarządza informacjami o produktach (nazwa, opis, cena itp.).
• Podgraf klientów: Zarządza danymi klientów (imię, adres, e-mail itp.).
• Podgraf zamówień: Zarządza informacjami o zamówieniach (ID zamówienia, ID klienta, ID produktów, łączna kwota itp.).

Każdy podgraf udostępnia API GraphQL, a brama federacyjna komponuje te API w jeden supergraf. Klient może następnie odpytać supergraf, aby pobrać informacje o produktach, klientach i zamówieniach w jednym żądaniu.

Na przykład, zapytanie w celu pobrania imienia klienta i historii jego zamówień mogłoby wyglądać tak:

query GetCustomerAndOrders($customerId: ID!) {
  customer(id: $customerId) {
    id
    name
    orders {
      id
      orderDate
      totalAmount
    }
  }
}

Brama federacyjna przekierowałaby to zapytanie do podgrafów Klientów i Zamówień, pobrała niezbędne dane i połączyła je w jedną odpowiedź.

Zalety Federacji GraphQL

• Uproszczony dostęp do danych: Klienci komunikują się z jednym punktem końcowym GraphQL, niezależnie od bazowych źródeł danych.
• Poprawiona wydajność: Pobieranie danych jest zoptymalizowane przez pobieranie tylko niezbędnych danych z każdego podgrafu.
• Zwiększona skalowalność: Każdy podgraf może być skalowany niezależnie, co pozwala na lepsze wykorzystanie zasobów.
• Zdecentralizowany rozwój: Zespoły mogą rozwijać i wdrażać podgrafy niezależnie, promując zwinność i innowacyjność.
• Zarządzanie schematem (schema governance): Brama federacyjna wymusza spójność i kompatybilność schematów między podgrafami.

Narzędzia dla Federacji GraphQL

• Apollo Federation: Popularna implementacja open-source Federacji GraphQL, dostarczająca bramę, rejestr schematów i narzędzia do budowania i zarządzania sfederowanymi API GraphQL. Apollo Federation jest znana ze swojej skalowalności i solidnej obsługi błędów.
• GraphQL Hive: To narzędzie oferuje rejestr schematów i zarządzanie dla sfederowanych usług GraphQL, zapewniając funkcje takie jak wykrywanie zmian, analiza użycia i sprawdzanie schematów. Zwiększa widoczność i kontrolę nad supergrafem.

Schema Stitching: Alternatywne Podejście

Czym jest Schema Stitching?

Schema Stitching to kolejna technika łączenia wielu schematów GraphQL w jeden, zunifikowany schemat. W przeciwieństwie do Federacji, Schema Stitching zazwyczaj wiąże się z bardziej manualnym procesem definiowania, jak typy i pola z różnych schematów są ze sobą połączone. Chociaż Federacja jest uważana za nowocześniejsze i bardziej solidne rozwiązanie, Schema Stitching może być realną opcją dla prostszych przypadków użycia lub podczas migracji z istniejących API GraphQL.

Jak działa Schema Stitching

1. Definicja schematu: Każda mikrousługa udostępnia API GraphQL z własnym schematem.
2. Logika łączenia (stitching logic): Warstwa łącząca (często implementowana przy użyciu bibliotek takich jak GraphQL Tools) definiuje, jak typy i pola z różnych schematów są ze sobą połączone. Wiąże się to z pisaniem funkcji resolverów, które pobierają dane z usług bazowych i mapują je na zunifikowany schemat.
3. Zunifikowany schemat: Warstwa łącząca łączy poszczególne schematy w jeden, zunifikowany schemat, który jest udostępniany klientowi.

Przykład: Łączenie Produktów i Opinii

Wyobraź sobie dwie oddzielne usługi GraphQL: jedną dla produktów, a drugą dla opinii.

• Usługa Produktów: Dostarcza informacji o produktach (ID, nazwa, opis, cena).
• Usługa Opinii: Dostarcza opinie o produktach (ID, ID produktu, ocena, komentarz).

Używając Schema Stitching, można stworzyć zunifikowany schemat, który pozwala klientom pobierać informacje o produktach i opinie w jednym zapytaniu.

Należałoby zdefiniować funkcję resolvera w warstwie łączącej, która pobiera opinie dla danego ID produktu z Usługi Opinii i dodaje je do typu `Product` w zunifikowanym schemacie.

// Example (Conceptual): Stitching logic using GraphQL Tools
const { stitchSchemas } = require('@graphql-tools/stitch');

const productsSchema = ... // Define your products schema
const reviewsSchema = ... // Define your reviews schema

const stitchedSchema = stitchSchemas({
  subschemas: [
    {
      schema: productsSchema,
    },
    {
      schema: reviewsSchema,
      transforms: [
        {
          transformSchema: (schema) => schema,
          transformRequest: (originalRequest) => {
            return originalRequest;
          },
          transformResult: (originalResult) => {
            return originalResult;
          }
        }
      ],
    },
  ],
  typeDefs: `
    extend type Product {
      reviews: [Review]
    }
  `,
  resolvers: {
    Product: {
      reviews: {
        resolve: (product, args, context, info) => {
          // Fetch reviews for the product from the Reviews Service
          return fetchReviewsForProduct(product.id);
        },
      },
    },
  },
});

Ten przykład demonstruje podstawową koncepcję łączenia schematów. Zauważ potrzebę niestandardowych resolverów do pobierania pola `reviews`. Ten dodatkowy narzut związany z kodowaniem resolverów dla każdej relacji może spowolnić proces rozwoju w porównaniu z użyciem Federacji.

Zalety Schema Stitching

• Zunifikowane API: Klienci uzyskują dostęp do jednego punktu końcowego GraphQL, co upraszcza dostęp do danych.
• Inkrementalna adopcja: Schema Stitching można wdrażać stopniowo, co pozwala na powolną migrację do zunifikowanego API.
• Elastyczność: Schema Stitching zapewnia większą kontrolę nad sposobem łączenia schematów, co pozwala na dostosowanie logiki łączenia do specyficznych potrzeb.

Wady Schema Stitching

• Manualna konfiguracja: Schema Stitching wymaga ręcznej konfiguracji logiki łączenia, co może być skomplikowane i czasochłonne.
• Narzut wydajnościowy: Funkcje resolverów mogą wprowadzać narzut wydajnościowy, zwłaszcza jeśli wiążą się ze skomplikowanymi transformacjami danych.
• Ograniczona skalowalność: Schema Stitching może być trudniejszy do skalowania niż Federacja, ponieważ logika łączenia jest zazwyczaj scentralizowana.
• Własność schematu: Może prowadzić do niejednoznaczności co do własności schematu, szczególnie jeśli różne zespoły zarządzają połączonymi usługami.

Narzędzia dla Schema Stitching

• GraphQL Tools: Popularna biblioteka do budowania i manipulowania schematami GraphQL, w tym wsparcie dla Schema Stitching.
• GraphQL Mesh: GraphQL Mesh pozwala używać języka zapytań GraphQL do dostępu do danych z różnych źródeł, takich jak API REST, bazy danych i gRPC. Może łączyć te API w zunifikowany schemat GraphQL.

Federacja GraphQL kontra Schema Stitching: Porównanie

Zarówno Federacja GraphQL, jak i Schema Stitching oferują sposoby łączenia wielu schematów GraphQL w jedno API, ale różnią się podejściem i możliwościami.

Cecha	Federacja GraphQL	Schema Stitching
Podejście	Rozproszona, zautomatyzowana kompozycja	Scentralizowana, manualna konfiguracja
Złożoność	Niższa złożoność utrzymania i skalowania	Wyższa złożoność z powodu manualnej logiki resolverów
Skalowalność	Zaprojektowana dla dużych, rozproszonych systemów	Mniej skalowalna, zazwyczaj używana w mniejszych aplikacjach
Zarządzanie schematem	Wbudowane zarządzanie schematem i walidacja	Wymaga manualnego zarządzania schematem i koordynacji
Narzędzia	Silny ekosystem narzędzi i bibliotek (np. Apollo Federation)	Wymaga więcej niestandardowych narzędzi i konfiguracji
Przypadki użycia	Architektury mikrousług, API na dużą skalę, zdecentralizowany rozwój	Mniejsze aplikacje, inkrementalna migracja, specyficzne wymagania dotyczące dostosowywania

Kiedy używać Federacji GraphQL: Wybierz Federację, gdy masz złożoną architekturę mikrousług, potrzebujesz skalować swoje API i chcesz dać niezależnym zespołom możliwość zarządzania własnymi podgrafami. Upraszcza to również zarządzanie schematem.

Kiedy używać Schema Stitching: Rozważ Schema Stitching, gdy masz prostsze API, potrzebujesz większej kontroli nad logiką łączenia lub migrujesz z istniejących API GraphQL. Bądź jednak świadomy potencjalnych złożoności i ograniczeń skalowalności.

Implementacja Uwierzytelniania i Autoryzacji

Niezależnie od tego, czy wybierzesz Federację GraphQL, czy Schema Stitching, implementacja uwierzytelniania i autoryzacji jest kluczowa dla zabezpieczenia Twojej frontendowej bramy API. Istnieje kilka podejść, które można zastosować:

• Uwierzytelnianie na poziomie bramy: Brama API obsługuje uwierzytelnianie i autoryzację przed przekierowaniem żądań do usług backendowych. To podejście centralizuje logikę bezpieczeństwa i upraszcza usługi backendowe. Popularne metody to walidacja JWT (JSON Web Token) i OAuth 2.0.
• Uwierzytelnianie na poziomie usługi: Każda usługa backendowa obsługuje własne uwierzytelnianie i autoryzację. To podejście zapewnia bardziej szczegółową kontrolę nad bezpieczeństwem, ale może być bardziej złożone w zarządzaniu.
• Podejście hybrydowe: Połączenie uwierzytelniania na poziomie bramy i na poziomie usługi. Brama obsługuje początkowe uwierzytelnienie, a usługi backendowe przeprowadzają bardziej szczegółowe kontrole autoryzacji.

Przykład: Uwierzytelnianie JWT z Apollo Federation

W przypadku Apollo Federation można skonfigurować bramę do walidacji tokenów JWT zawartych w nagłówkach żądania. Brama może następnie przekazać informacje o użytkowniku wyodrębnione z tokenu do podgrafów, które mogą wykorzystać te informacje do autoryzacji.

// Example (Conceptual): Apollo Gateway configuration with JWT validation
const { ApolloGateway } = require('@apollo/gateway');

const gateway = new ApolloGateway({
  serviceList: [
    // ... your subgraph configurations
  ],
  buildService: ({ name, url }) => {
    return new MyCustomService({
      name,  // Name of the subgraph
      url,   // URL of the subgraph
    });
  },
});

class MyCustomService extends RemoteGraphQLDataSource {
  willSendRequest({ request, context }) {
    // Get the user from the context
    const user = context.user;

    // Add the user's ID to the request headers
    if (user) {
      request.http.headers.set('user-id', user.id);
    }
  }
}

W tym przykładzie tworzona jest niestandardowa usługa w celu modyfikacji wychodzących żądań, aby zawierały ID użytkownika pochodzące z JWT. Usługi podrzędne mogą następnie używać tego ID do sprawdzania autoryzacji.

Strategie Buforowania dla Optymalizacji Wydajności

Buforowanie (caching) jest niezbędne do poprawy wydajności frontendowej bramy API. Buforując często używane dane, można zmniejszyć obciążenie usług backendowych i poprawić czasy odpowiedzi dla klientów. Oto niektóre strategie buforowania:

• Buforowanie HTTP: Wykorzystaj mechanizmy buforowania HTTP (np. nagłówki `Cache-Control`), aby buforować odpowiedzi w przeglądarce i pośrednich serwerach proxy.
• Buforowanie w pamięci (In-Memory Caching): Użyj pamięci podręcznych w pamięci (np. Redis, Memcached), aby buforować często używane dane na bramie.
• Buforowanie CDN: Wykorzystaj Sieci Dostarczania Treści (CDN) do buforowania statycznych zasobów i odpowiedzi API bliżej klienta.
• Buforowanie zapytań GraphQL: Buforuj wyniki zapytań GraphQL na podstawie ich ciągu zapytania i zmiennych. Może to być szczególnie skuteczne w przypadku często wykonywanych zapytań. Apollo Server oferuje wbudowane wsparcie dla buforowania zapytań.

Podczas implementacji buforowania należy rozważyć strategie unieważniania pamięci podręcznej, aby zapewnić, że klienci otrzymują aktualne dane. Typowe strategie obejmują:

• Wygaśnięcie czasowe: Ustaw stały czas wygaśnięcia dla buforowanych danych.
• Unieważnianie oparte na zdarzeniach: Unieważnij pamięć podręczną, gdy dane w usługach backendowych ulegną zmianie. Można to osiągnąć za pomocą webhooków lub kolejek komunikatów.

Monitoring i Obserwowalność

Monitoring i obserwowalność są kluczowe dla zapewnienia kondycji i wydajności Twojej frontendowej bramy API. Zaimplementuj kompleksowy monitoring, aby śledzić kluczowe metryki, takie jak:

• Opóźnienie żądania: Czas potrzebny na przetworzenie żądania.
• Wskaźnik błędów: Procent żądań, które kończą się błędami.
• Przepustowość: Liczba przetworzonych żądań na jednostkę czasu.
• Wykorzystanie zasobów: Użycie procesora, pamięci i sieci przez bramę i usługi backendowe.

Używaj śledzenia (tracing) do monitorowania żądań w miarę ich przepływu przez system, identyfikując wąskie gardła i problemy z wydajnością. Logowanie dostarcza cennych informacji na temat zachowania bramy i usług backendowych.

Narzędzia do monitoringu i obserwowalności obejmują:

• Prometheus: System monitorowania i alertowania open-source.
• Grafana: Narzędzie do wizualizacji danych i monitorowania.
• Jaeger: System śledzenia rozproszonego open-source.
• Datadog: Platforma monitorowania i bezpieczeństwa dla aplikacji chmurowych.
• New Relic: Platforma cyfrowej inteligencji do monitorowania i poprawy wydajności oprogramowania.

Implementując solidny monitoring i obserwowalność, możesz proaktywnie identyfikować i rozwiązywać problemy, zapewniając niezawodność i wydajność swojej frontendowej bramy API.

Podsumowanie

Frontendowa brama API zbudowana z wykorzystaniem Federacji GraphQL lub Schema Stitching może znacznie uprościć dostęp do danych, poprawić wydajność i zwiększyć komfort pracy deweloperów w nowoczesnych aplikacjach internetowych. Federacja GraphQL zapewnia potężne i skalowalne rozwiązanie do komponowania rozproszonych API GraphQL, podczas gdy Schema Stitching oferuje bardziej elastyczne podejście do łączenia istniejących schematów. Starannie rozważając specyficzne wymagania aplikacji i kompromisy między tymi technikami, można wybrać najlepsze podejście do budowy solidnej i wydajnej frontendowej bramy API.

Pamiętaj o wdrożeniu odpowiedniego uwierzytelniania i autoryzacji, strategii buforowania oraz monitoringu i obserwowalności, aby zapewnić bezpieczeństwo, wydajność i niezawodność swojej bramy. Stosując te najlepsze praktyki, możesz w pełni wykorzystać potencjał GraphQL i tworzyć nowoczesne aplikacje internetowe, które zapewniają wyjątkowe doświadczenia użytkownika.